RESTful (Representational State Transfer) / REST API

  • A REST API is a specific type of API that uses a set of conventions and best practices to facilitate communication between client and server.

  • REST is designed to be scalable and can be easily used in distributed web applications.

  • RESTful describes an implementation that follows this concept. In other words, an API is RESTful if it follows REST principles.

  • Resources Represented by URLs :

    • Resources (data or system entities such as users, products, etc.) are identified by URLs (Uniform Resource Locators).

    • Example:

      • /users :

        • Represents the collection of users.

      • /users/1 :

        • Represents a specific user with ID 1.

  • Data Representations :

    • Resource data can be represented in different formats such as JSON, XML, HTML, etc.

    • Client and server negotiate representation using HTTP headers like Content-Type  and Accept .

  • Stateless :

    • Each request to the server must contain all information needed to be processed.

    • The server does not maintain client state between requests which makes the system more scalable.

  • HATEOAS (Hypermedia as the Engine of Application State) :

    • Optional but part of the REST idea. Resources include links to other resources or related actions guiding the client on what to do next.

    • Example: 

    {
  "id": 1,
  "name": "John Doe",
  "links": {
    "self": "/users/1",
    "posts": "/users/1/posts"
  }
}

  • Layers :

    • REST architecture allows separation into layers like proxies, load balancers and caches without the clients noticing.

Queries

  • .

    • Queries for /oi  will be: 

    {
    msg: 'aaaaaaa',
    test: 123
}

CRUD Operations (Create, Read, Update, Delete)

  • Represent the basic actions that can be performed on resources, and each of them is mapped to specific HTTP methods in a REST API.

  • Each operation on resources uses standard HTTP methods.

  • GET :

    • Retrieves data from a resource.

  • POST :

    • Creates a new resource.

  • PUT  or PATCH :

    • Updates an existing resource.

  • DELETE :

    • Removes a resource.

Principles

  • Client-Server

    • The architecture should separate the user interface (client) from data storage logic (server). This allows both to evolve independently.

  • Stateless

    • Each client request to the server must contain all the information necessary to understand and process the request.

  • Cacheable

    • Responses should be explicitly marked as cacheable or non-cacheable. This improves performance by allowing responses to be stored and reused.

  • Layered System

    • The architecture can be composed of multiple layers, such as intermediaries, proxies and gateways, which can facilitate scalability and security without the client knowing about these layers.

  • Uniform Interface

    • The interface between client and server should be standardized, making communication easier. This includes using URIs to identify resources and HTTP methods to operate on them.

  • Resources

    • REST APIs treat everything as a resource identified by a URL. Operations on these resources are performed using HTTP methods (GET, POST, PUT, DELETE, etc.).

  • Representations

    • Resources can be represented in different formats, such as JSON or XML.

Headers
Benefits

  • Simple design and usage.

  • Language and platform independent.

  • Easily scalable and extensible.

  • Leverages native HTTP features like caching and access control.

Examples

  • List all books:

    • Request :

      • GET /books

    • Response : 

      [
  {"id": 1, "title": "Book A"},
  {"id": 2, "title": "Book B"}
]

  • Get details of a specific book:

    • Request :

      • GET /books/1

    • Response : 

      {"id": 1, "title": "Book A", "author": "Author X"}

Debug